Copyright: Copyright ® 1996 Visual Solutions Ltd


Contents
DBFilter Contents

Support - EMail 72361.2107@compuserve.com or the 3rdParty section of the CIS Delphi forum subject DBFILTER.

Introduction

Welcome to DB Filter v2.0.
DB Filter provides a set of components that give full access to the BDE Filtering Language for Delphi 1.0.

What are Filters?

Creating A Filter

Components

TFilter

TFilterFunc

TFilter Designer

TFilterCondition Object

Reference

Filter Language

Installation

History

FAQ's

Registration and Support

Licence Agreement

Index

Glossary


What Are Filters
What Are Filters?

Filters are similar to queries in that they query a dataset to find records that match certain criteria (conditions ) but they differ in two important aspects; Firstly they do not rely on or use the current index so that a "live" or editable result set can be returned regardless of the current sort order. Secondly they query one record at a time rather than the entire dataset at once so they appear to be very fast as they return control to your application as soon as a matching record is found (or in the case of a grid control as soon as enough records can be found to fill the grid).

Filters are also useful as they can be applied to an existing Table or Query, so they can for example be used to subquery a TQuery's result set without having to rerun the query or to on the fly limit the records viewed by a form without the need to run queries.

In its simplest form a filter lets you compare a field in a record against a constant value and if it matches, the record is displayed, if it does not the record is not displayed.


Creating A Filter
Creating A Filter - Concepts

This section is intended to introduce the concepts involved in creating a BDE Filter rather than to be a literal definition of the construction of a filter.

Adding Filter Conditions

The BDE Filter engine cannot process Filter Conditions individually, it must instead process all conditions that make up a BDE Filter in one go. We must therefore have in itermediate stage where you can sequentialy add conditions to the filter definition.
So the first stage in creating a filter involves adding conditions, which are temporarily stored in FilterCondition Objects, to a TList. These are not the conditions as the BDE Engine would recognise them but represent a form that the TFilter component can readily convert but which at the same time are easy to comprehend by the Designer/User.

A Filter Condition here is represented by four parameters FieldName, Operator, Value, and Link as in  CustomerName,LIKE,'BILL',canAND.

When this stage is complete the TList holds all the conditions in the order that they will be applied when constructing a BDE Filter.

Preparing a Filter

In the second stage the filter is prepared. The TList is processed by TFilter's own parsing engine and these conditions are compiled into a single filter in the form that is understood by the BDE Engine. This filter is held in a single memory block. This is then submitted to the BDE Engine for it to actually construct the filter inside the BDE Engine and allocate any resources it will need. On returning the memory block associated with the filter is released as the filter now exists entirely inside the BDE Engine, a Handle to the Filter in the BDE Engine is also returned.
The original TLIst and FilterCondition objects now play no further part in the use of the FIlter.

Using a Filter

The third stage is to use the BDE Filter, previously we noted that a Handle to the filter is returned by the BDE Engine whne it constructs the filter, we now use this Handle in calls to the Engine to activate or deactivate this filter.
When we are totaly finished with the filter we can instruct the BDE Engine to Drop or discard the filter, this deletes the filter and releases any resources that the BDE Engine itself allocated in respect of this filter.

It is important to note that this is only releasing the BDE's own resources allocated for the filter, it does not effect the TFilter object in Delphi, its TList still exists as do all the FilterCondition objects.

Although TFilter supports multicondition filters internally it is also possible to use more than one TFilter component to apply several filters to a dataset at the same time.

Usually when you carry out an action you identify the filter by its handle however you can address all filters for a dataset by leaving the handle property as nil. ie you can drop all filters for a  dataset by using the appropriate method but leavng the Handle parameter as nil.

When you close a dataset the BDE Engine automatically drops all filters associated with that dataset.


TFilter Methods
TFilter Methods:

procedure Add (AFieldName: StringFN; AOperator: CANOp; AFieldValue: string; ANextOperator: CANOp )
procedure AddFilterCondition (AFilterCondition:TFilterCondition)
procedure DeleteFilterCondition (Index:integer)
procedure ClearFilterConditions
procedure Prepare
procedure UnPrepare
procedure Activate
procedure DeActivate
procedure RemoveFilter
procedure DBActivate (hFilter :hDBiFIlter)
procedure DBDeActivate (hFIlter :hDBiFilter)
procedure DBDropFilter (hFilter :hDBiFilter)
function    DBAddFilter :hDBiFilter


TFilter Properties

 Dataset :TDataset
 Conditions [Index:integer]:TFilterCondition; default
 FilterCount :integer
 Prepared :Boolean
 Active :Boolean
 Handle :hDBiFilter
 GoFirst :Boolean
 AutoActivate :Boolean
AutoPack :Boolean


TFilter
TFilter Component

Properties	 Methods

Unit

DBFilter

Description

TFilter is derived directly from a TComponent and provides access to filter functions for BDE datasets.

Set the Dataset property to the BDE dataset this filter will be applied to.

The filter conditions are defined either via the FilterDesigner, which is accessed by double clicking the TFilter component at designtime or through adding filter condtions by calling one of the methods listed below from a procedure or by creating and using the FilterDesigner at run time. Filter conditions can be joined by AND or OR to create complex expressions, and can apply to any field except Blobs and their derivatives.

Use the Add method to construct a filter condition. The AddFilterCondition method is used to add a previously created FilterCondition Object to the current filter, DeleteFilterCondition and ClearFilterConditions method remove an individual FilterCondition object or all FilterConditions respectively.

The Conditions property gives you direct access to the individual FilterCondition objects. This property is the default indexed property so that MyFilter[0] and MyFilter.Conditions[0] are both legal and point to the same FilterCondition object. The FilterCount property returns the number of filter conditions defined in the current filter.

Setting the Prepared property to true calls the Prepare method which submits the FilterConditions to the BDE Engine whilst setting the property to False calls the UnPrepare method and drops the filter and clears all FilterConditions. To use the BDE Filter either set the Active property or call the Activate and DeActivate methods.

The Handle property is the DBiFilter Handle and the Dataset property is the Dataset that the filter is applied to.


TFilterFunc Methods
TFilterFunc Methods:

procedure Activate
procedure DeActivate


TFilterFunc Properties
TFilterFunc Properties:

 Dataset :TDataset
 Active :boolean
 Handle :hDBiFilter
 AutoActivate :boolean
 GoFirst :boolean;
 OnFilterRecord :TFilterEvent
 BeforeDatasetClose:TDatasetNotifyEvent
 AfterDatasetOpen:TDatasetNotifyEvent


TFilterFunc
TFilterFunc Component

Properties	Methods

Unit

DBFilter

Description

The FilterFunc component allows you to filter a dataset using your own callback function. The component has an OnFilter event which you can use to write your own procedure that can access any field in the dataset (or any other dataset) and then simply return True or False to determine wether the record should be displayed.
Fields can be accessed by FieldByName() functions. You must not issue any command that moves the record position or changes the dataset state (ie Next or Edit in the middle of your filter function is just asking for trouble).

Set the Dataset property to identify the datset that the filter will be applied to. Set the OnFilterRecord property to the procedure that will handle the OnFilter event. Set the Active property to True or False or use the Activate or DeActivate methods to apply the filter. The Handle property is the HDBiFilter that identifies the filter to the BDE Engine.
Set the AutoActivate property to automatically apply the Filter when the component is loaded.
Set the GoFirst property to force the dataset to be moved to the first record when the filter is applied, if this is set to false the record pointer will be positioned at the next record that matches the filter condition, this also applies to when the filter is removed.

In order to function correctly the TFilterFunc component hooks the BeforeClose and AfterOpen events of the Dataset it is attached to. If you wish to use these events you should instead use the similar BeforeDatasetClose  and AfterDatasetOpen events of the TFilterFunc component which will be called immediately the TFilterFunc component has finished its processing of these events.


Filter Property

Applies to

 TFilterDesigner

Declaration

property Filter: TFilter

Description

TFilter points to the TFilter component that is both the source for the TFilterDesigner and the destination of the designed filter.


TFilterDesigner Properties

 Filter :TFilter


TFilter Designer
TFilter Designer Form

Properties

Unit

DBFltReg,FltFrm

Description

The Filter Designer provides a prepackaged form that can be used by you and your end users to build filters at run time or design time in a simple fashion.
The Filter Designer comes in two variations, the run time version places emphasis on simplicity, so the form uses a subset of the Filter Language to provide a very easy to use Filter Design Tool for end users. You will also note that the filter operators are named differently than in the Filter Language again this is to make it easier for end users to comprehend.
The design time version works in the same way but provides additional Filter commands and the ability to construct advanced complex filters. To open the designtime FilterDesigner double click on the TFilter component.

To use the run time FilterDesigner add the FiltFrm unit to the uses clause of your form then create and use an instance of the TFilterForm, see the demo code for an example.

Before the FilterDesigner is shown it requires one property Filter to be set to indicate the TFilter component that FilterDesigner will be designing a filter for. The TFilter component must have at least its Dataset property set before the Designer is activated.

If there is an existing filter defined in the TFilter (ie there are already FilterCondition Objects ) then the Designer will read in those FilterConditions so that you can "Edit" the filter.

When you are finished you click the OK Button and the Filter is sent to the TFilter component, the Designer will first Deactivate and then clear any filter that is currently in the TFilter before creating the newly defined Filter.


TFilterCondition Methods

Add ( AFieldName: StringFN; AOperator: CANOp; AFieldValue: string; ANextOperator: CANOp)


TFilterCondition Properties

 Dataset :TDataset
 FieldName :StringFN
 Operator :CANOp
 FieldValue :String
 NextOperator :CANOp
 FieldDataType :TFieldType
 ValueSize :integer
 Partial :Boolean
 AsString :string


AsString
AsString Property

Applies to

TFilterCondition component

Declaration

property AsString : string

Description

This property can be used to set or get the filter in a deliminated string value. The FieldName, Operator, FieldValue and NextOperator property are returned in a string deliminated with a ';'.


Partial
Partial Property

Applies to

TFilterCondition component

Declaration

property Partial :boolean

Description

This property must be set to True for wildcard conditions on string fields.


ValueSize
ValueSize Property

Applies to

TFilterCondition component

Declaration

property ValueSize :integer

Description

This property indicates the size of the FieldValue property.

For strings it is the length of the string LESS any wildcard characters, for other fields it is the datasize for that type.


FieldDataType
FieldDataType Property

Applies to

TFilterCondition component

Declaration

property FieldDataType :TDatatype

Description

Set this property to the fieldtype of the field that the FilterCondition applies to. If there is no field for this FilterCondition then the value is ftUnknown.


NextOperator
NextOperator Property

Applies to

TFilterCondition component

Declaration

property NextOperator :CANOp

Description

Set this property to the CANOp that specified the link between this FilterCondition and the next FilterCondition. The value is canNOTDEFINED if there is no link between this and the next condition.


FieldValue
FieldValue Property

Applies to

TFilterCondition component

Declaration

property FieldValue :string

Description

Set this property to the constant value that you will compare fields against in this FilterCondition.


Operator
Operator Property

Applies to

TFilterCondition component

Declaration

property Operator :CANOp

Description

Set this property to the CANOP operator for this FilterCondition.


FieldName
FieldName Property

Applies to

 TFilterCondition component

Declaration

property FieldName :FNstring

Description

Set this property to the name of the field the FilterCondition will be applied to.


TFilterCondition Object

 Properties	Methods

Unit

DBFilter

Description

The TFilterCondition object temporarily holds FilterConditions whilst you build a filter definition before preparing the BDE Filter. You can access the FilterConditions through the Conditions property of the TFilter component.

The Dataset property identifies the dataset this filter condition will be applied to. The FieldName property identifies the name of the field in the dataset this filter condition applies to. The Operator is the CANOp expression to use. FieldValue is the constant value to apply. FieldDataType identifies the field type. ValueSize is the size of the FieldValue, for strings it is the length of the string constant EXCLUDING any wildcard parameter ("..") for other datatypes it is the datatype size. Partial is set to true for all Wildcard matches.

The AsString property gets or sets the properties as a delimited list of FieldName; Operator; FieldValue; NextOperator.

The add method sets the properties from there constituent parts.

The Dataset property must be set before the other properties are set or the filter condition will not be valid.


TBDEFilter Object

Unit

DBFilter

Description

The TBDEFilter Object is currently unused but can be used to hold HDbIFilters that are no longer attached to a TFilter component, you may for example create a series of filters and store them in TBDEFilter objects attached to a stringlist that can be selected by the user.


Filter Language

The following lists the enitre BDE CANOp language that the TFilter component understands. When setting a FilterCondition from a procedure or when saving or loading a filter from a text file the FilterConditions must be written using this language. The equivalent command from the Filter Designer is shown after the *

Comparison

canNOTDEFINED,    {                      (*)                    }
canISBLANK,       {is operand blank.     (*Is Blank)            }
canNOTBLANK,      {is operand not blank. (*Is Not Blank)        }
canEQ,            {equal.                (*Is Equal to)         }
canNE,            {NOT equal.            (*Not Equal to)        }
canGT,            {greater than.         (*Greater than)        }
canLT,            {less than.            (*Less than)           }
canGE,            {greater or equal.     (*Greater or Equal to) }
canLE,            {less or equal.        (*Less or Equal to)    }

Links

canNOTDEFINED,    {                      (*none)                }
canAND,           { AND                  (*And)                 }
canOR             { OR                   (*Or)                  }
canNOT            { NOT                  (*Not)                 }
canCONT           { CONTINUE             (*Continue)            }

DBFilter supports a limited wildcard search for string fields, use the canEQ operator and place ".."
after the value to match anything ie all values  starting with Delp, 'Delp.." searching is case
insenstive with wildcards.

A Continue link is like the High value in a range, when the condition is met the filter will no longer evaluate any further records. In the current version only a single condition can be placed after a Continue condition, ie you cannot AND or OR additional conditions after the Continue condition..


Installation

You may make one copy of this software, for backup purposes only, in addition to the installation described below.

Unzip the file DBFLT.ZIP using the -d parameter ie PKUNZIP -D DBFLT.ZIP.

This (hopefully )will create a directory structure as follows;

\VCLLIB - DB Filter  v2.0 Components and help file.
\VCLSRC - DB Filter v2.0 Source files.
\DEMO - Demo application.
README.TXT - Readme file.

Copy the contents of the VCLIB directory to the \DELPHI\LIB directory and install the units DBFILTER.DCU, DBFLTREG.DCU and FLDCOMBO.DCU following the standard Delphi instructions for installing components.

This will install TFilterFunc and TFilter components on the Data Access page of the VCL.

To run the DEMO application:
Make sure  you have the DEMO alias set for the delphi DEMO DB that comes with Delphi 1.0

Start Delphi, open and compile the project PROJECT1.


History

Version 2.0
Major changes

TStoredFilter and TFilter combined into a single component.
RunTime FilterDesigner component editor added.
TFilterFunc now bound directly to the TDataset not a TDatasource.
Surfaced the properties of the TFilterCondition Objects for advanced users.

Other Changes

Added AutoActivate and GoFirst properties.

Expanded filter conditions to include NOT and CONTINUE

Improved error handling - Failed filters no longer leave the stack in an unstable condition.

Corrected error in handling non string filter conditions.

Added debugging mode ( registered version only ).

Improved handling of BOF/EOF condition in TFilterFunc.

Detection of Filter being dropped by other components or the dataset being deactivated.

Detection of attempts to Activate,DeActivate,Drop against inactive datasets.

A bug in the FldCombo Unit caused a GPF if the datasource of the Visual Filter Designer is changed on the Fly.
Another bug in the FldCombo Unit returned a blank field name if the first item of the first Field Combo box in the Visual Filter Designer is selected.
A bug in the Visual Filter Designer - Only the first Field Combo was of the type FLDCOMBO the rest were standard Combo's, although the standard combos' could display FieldDisplayLabels they are unable to translate them back to FieldNames that is required by the Filter Unit. The standard combos have now been replaced by FLDCOMBO's which support this capability.

Version 1.0

Initial release.


FAQ
FAQ's

This section contain FAQ's, random thoughts, hints or suggestions.

How do I create a filter

Creating a TFilter

Complex Filters

Complex filters can be built using TFilter component but require a bit more thought.
To add a NOT condition to a filter you add a condition object with only the LinkOperator defined, as Not (canNOT), then add another condition object with the filter condition you want and define its LinkOperator as None (canNOTDEFINED). See the demo filter component Filter1 for an example of this technique. Double click on the TFilter Component to activate the FilterDesigner and display the filter definition.

Creating a Filter in a text file

It is possible to both save and load a filter definition from a text file. The filter is specifed in exactly the same way as you would arrange the parameters for the TFilter components add method, that is FieldName, Operator, FieldValue, LinkOperator. The parameters must be deliminated by a ';' and each condition is placed on a separate line. Here is an example of a such a filter definition.

CustNo;canGT;1450;canAND

Company;canEQ;B..;canNOTDEFINED


Creating A TFilter

Follow these steps to create a filter:

1 	Drop a TFilter component on to your form.

2 	Set the Dataset property to the dataset you wish to apply a filter to.

3 	If you wish the filter to go to the first record when it is activated set the GoFirst property to True.

4 	If you wish the Filter to be automatically activated when the form is loaded set AutoActivate to True.

5 	Double Click on the compoent to open the FilterDesigner.

6 	Chose the Filter options you wish to apply. When you are finished click the OK button.

The Filter is now defined and is ready to use in your application.


Registration and Support

Registration

The demo version of DB Filter v2.0 has a limited time use, you MUST register to receive the unrestricted version and to be able to legally distribute applications containing this component.

COMPUSERVE USERS: SWREG Orders Only

You can register via CIS SWREG forum. GO SWREG and follow the instructions for registering shareware.

PRICE - US$55.00
The Registration ID for DBFilter v2.0 is 9438.

To ensure that you get the latest version, CIS will notify us the day of your order and we will Email the latest full registered version of our software to your CIS address, usually within 48hrs.

INTERNET USERS: CREDIT CARD Orders Only
You can order with MC, Visa, Amex, or Discover from Public (software) Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398 or by CIS Email to 71355,470. You can also mail credit card orders to PsL at P.O.Box 35705, Houston, TX 77235-5705.

PRICE - US$60.00
The Registration ID for DBFilter is 14541.

THE ABOVE NUMBERS ARE FOR CREDIT CARD ORDERS ONLY.

THE AUTHOR OF THIS PROGRAM CANNOT BE REACHED AT THESE NUMBERS.

You can also order OnLine by visiting our Web Site at :

http://ourworld.compuserve.com/homepages/robedgar/

follow the instructions for software registration.

Any questions about the status of the shipment of the order, refunds, registration options, product details, technical support, volume discounts, dealer pricing, site licenses, non-credit card orders, etc, must be directed to  72361.2107@compuserve.com.

To insure that you get the latest version, PsL will notify us the day of your order and we will Email directly to you the password that is required to unzip the latest full registered version of our software which is available for download from our Web Site's Software Registration page.

Registered users will receive:

1 	Full unrestricted version of DB Filter v2.0 .

2 	Full component source code.

3 	Licence agreement, allowing you to legally distribute applications containing the DB Filter components, plus allowing the help file or its contents to be distributed or copied or included in your own application help file. Help file RTF source documents available upon request.

4 	Free future minor version upgrades to DB Filter when available.

Support

Support is currently only available via EMail!!!!

EMail to CIS ID 72361,2107 - Rob Edgar (Internet Users: 72361.2107@compuserve.com)

or send Email  to the CIS DELPHI forum. ThirdPartyTools section. with the subject DBFILTER.


License Agreement Release
License Agreement - Release Version

Important

By using this software you accept the following terms of this License Agreement.  If you do not agree with these terms, you should not use the software and promptly return it for a refund.

Ownership

Visual Solutions Ltd. retains the ownership of this copy of the enclosed software package.  It is licensed to you for use under the following conditions:

You May

You may transfer this software to another party if the other party agrees to the terms and conditions of the agreement and completes and returns a registration card to Visual Solutions Ltd.  The registration card is available by writing to Visual Solutions Ltd.  If you transfer the software, you must simultaneously transfer all documentation and related disks.
You may merge this software with your own software or code provided that the primary purpose of your software is not database access control, such software may be distributed without payment of a royalty fee.
You may copy any part of this help file, with the exception of this license agreement, for the sole purpose of informing the users of your software on how to use the features of the DB Filter.

You May Not

You may not copy the documentation or software except as described in the installation section of this manual.  You may not distribute, rent, sub-license or lease the software or documentation, including translating, decompiling, disassembling, or creating derivative works.  You may not reverse-engineer any part of this software, or produce any derivative work.  You may not make telecommunication transmittal of this software.

Termination

This license and your right to use this software automatically terminates if you fail to comply with any provision of this license agreement.

Rights

Visual Solutions Ltd. retains all rights not expressly granted.  Nothing in this license agreement constitutes a waiver of Visual Solutions Ltd.'s rights under the H.K. copyright laws or any other law.

Limited Warranty

If you discover physical defects in the media, Visual Solutions Ltd. will replace the media or documentation at no charge to you, provided you return the item to be replaced with proof of payment to Visual Solutions Ltd. during the 90-day period after having taken delivery of the software.

License Agreement

Visual Solutions Ltd.excludes any and all implied warranties, including warranties of merchantability and fitness for a particular purpose and limits your remedy to return the software and documentation to Visual Solutions Ltd. for replacement.
Although Visual Solutions Ltd. has tested the software and reviewed the documentation, Visual Solutions Ltd. MAKES NO WARRANTY OF REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS SOFTWARE OR DOCUMENTATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.  AS A RESULT, THIS SOFTWARE AND DOCUMENTATION ARE LICENSED "AS IS" AND YOU, THE LICENSEE, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE.

IN NO EVENT WILL Visual Solutions Ltd. BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION, even if advised of the possibility of such damages. In particular, Visual Solutions Ltd. shall have no liability for any data stored or processed with this software, including the costs of recovering such data.
THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESSED OR IMPLIED.  No Visual Solutions Ltd. dealer, agent, or employee is authorized to make any modifications or additions to this warranty.

Information in this document is subject to change without notice and does not represent a commitment on the part of Visual Solutions Ltd.  The software described in this document is furnished under this license agreement.  The software may be used or copied only in accordance with the terms of the
agreement.  It is against the law to copy the software on any medium except as specifically allowed in the license agreement.  No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the written permission of Visual Solutions Ltd.

Some countries do not allow the exclusion of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you.  This warranty gives you specific legal rights, and you may also have other rights which vary from country to country.


Index

A

Activate

Active

Add Method

AddFilter

AddFilterCondition Method

AfterDatasetOpen Property

AutoActivate Property

B

BeforeDatasetClose Property

C

ClearFilterConditions

Conditions

Contents

Creating A Filter

Creating A TFilter

D

Dataset

DBActivateFilter Method

DBAddFilter Method

DBDeActivateFilter Method

DBDropFilter Method

DeActivate

DeleteFilterCondition

F

Filter Language

FilterCount Property

G

Glossary

GoFirst Property

H

Handle

HFilter

History

I

Index

Installation

L

License Agreement Release

License Agreement

LoadFromFile Method

M

FAQ's

O

OnFilterRecord

P

Prepare

Prepared

R

Registration and Support

RemoveFilter

S

SaveToFile Method

T

TBDEFilter Object

TFilter Designer

TFilter

TFilterCondition Object

TFilterFunc

U

Unprepare

W

What Are Filters


Glossary

A

Activate

Active

Add

AddFilter

AddFilterCondition

AutoActivate

C

ClearFilterConditions

Conditions

D

Dataset

Datasource

DBActivate

DBAddFilter

DBDeActivate

DBDropFilter

DeActivate

DeleteFilterCondition

F

FilterCount

G

GoFirst

H

Handle

HFilter

O

OnFilterRecord

P

Prepare

Prepared

R

RemoveFilter

S

U

UnPrepare


Activate
KActivate Method

Applies to

TFilter, TFilterFunc components

Declaration

procedure Activate;

Description

Activates the current filter. Depending on the GoFirst property the record position will either be moved to the first record in the dataset matching the filters criteria or it will be moved to the next record after the current record that matches the criteria.

If there is an unprepared filter definition this procedure will first prepare and then activate the filter.


Active
KActive Property

Applies to

TFilter, TFilterFunc components

Declaration

property Active: Boolean

Description

Set the Active property to True to apply the filter to a dataset. Set it to False to temporarily remove the Filter. Setting the property to False does not release the resources allocated by the BDE Engine for this filter, you should set prepared to False or use the RemoveFilter method to release all resources.


Add Method

Applies to

TFilter,   TFilterCondition components

Declaration

procedure Add( AFieldName:StringFN; AOperator:CANOp; AFieldValue:string; NextOperator: CANOp );

Description

Sets the properties of the FilterCondition to the values specified by the parameters of this method.

For the TFilter component this method first creates a TFilterCondition object, then fills its properties from the supplied parameters and finally adds the object to the TList of conditions.

Use the AddFilterCondition Method to add TFilterCondition objects you have created yourself.


AddFilter
AddFilter Method

Applies to

TFilter component

Declaration

procedure AddFilter;

Description

Takes the current filter conditions and prepares it by submitting it to the BDE engine. The BDE engine adds the filter to the dataset but does not activate it.


AddFilterCondition Method

Applies to

TFilter component

Declaration

procedure AddFilterCondition (AFilterCondition : TFilterCondition )

Description

Adds the FilterCondition object identified in the parameter. Use the Add method to construct and add a filter condition from its constituant parts.
This is a low level procedure that allows you to independently create FilterCondition objects, manually set the object properties and then add them to the filter conditon list.


AfterDatasetOpen Property

Applies to

TFilterFunc component

Declaration

property AfterDatasetOpen: TDatasetNotifyEvent;

Description

This is the event generated after a dataset is opened.


AutoPack Property

Applies to

TFilter

Declaration

property AutoPack: boolean;

Description

Setting this property to true will cause the FilterCondition objects held in the TList to be deleted immediately after the filter is prepared for the first time.

Please note that although this is useful in releasing resources, unless you have a way to recreate the FilterConditions the filter will not be able to be used again once it has been dropped by the BDE Engine.


AutoActivate Property

Applies to

TFilter, TFilterFunc

Declaration

property AutoActivate: boolean;

Description

Set to true to cause the filter to be prepared and activated when the component is loaded. Otherwise you must explicitly activate the filter.


BeforeDatasetClose Property

Applies to

TFilterFunc component

Declaration

property AfterDatasetOpen: TDatasetNotifyEvent;

Description

The BeforeDatasetClose property is the event generated before the dataset is closed.


ClearFilterConditions
ClearFilterConditions Method

Applies to

TFilter component

Declaration

procedure ClearFilterConditions;

Description

Removes all filter conditions from the current filter list by freeing the FilterCondition objects


Conditions
KConditions Method

Applies to

TFilter component

Declaration

property Conditions[Index:integer]: TFilterCondition

Description

The property contains the FilterCondition objects that make up a filter. Because the Conditions property is a TList you can add, delete, insert and move using the respective TList methods. Provides direct access to the individual filterconditions. This property is the default property for the TFilter so that MyFilter[1] and MyFilter.Conditions[1] both refer to the same FilterCondition object


Dataset
Dataset Property

Applies to

TFilter, TFilterFunc and TFilterCondition components

Declaration

property DataSet: TDataSet

Description

Dataset specifies the dataset component ( TTable, TQuery, and TStoredProc) that the filter will be applied to.

If there is a prepared or active filter when this property is set the filter will be deactivated and removed. For the TFilter component this will also result in the FilterConditions objects being freed.


DBActivateFilter Method

Applies to

TFilter component

Declaration

procedure DBActivateFilter (hFilter :hDBiFilter);

Description

This is a low level procedure allowing you direct access to the BDE Engine. The procedure activates the BDE Filter identified by the hFilter parameter for the components dataset.You should normaly set the Active property to true or use the Activate method.

If the hFilter is nil then all filters for the dataset will be activated.


DBAddFilter Method

Applies to

TFilter component

Declaration

function DBAddFilter:hDBiFilter

Description

This is a low level function that takes the filter currently defined by the TList of FIlterCondition Objects and constructs a FilterBlock and submits this block to the BDE Engine, if the block is accepted by the BDE Engine then the function will return a handle to the filter.

You would not normally use this procedure instead set the Prepared property to True or use the Prepare method.


DBDeActivateFilter Method

Applies to

TFilter component

Declaration

procedure DBDeActivate ( hFilter :hDBiFilter);

Description

This is a low level procedure that gives you direct access to the BDE Engine. The procedure deactivates the filter defined by the hFilter parameter. If the hFilter parameter is nil then all filters for the dataset will be deactivated.
You will normally use the DeActivate method or set the Active property to False.


DBDropFilter Method

Applies to

TFilter component

Declaration

procedure DBDropFilter (hFilter :hDBiFilter)

Description

This is a low level procedure that provides direct access to the BDE Engine. This procedure drops the filter identified by the hFilter parameter. Dropping the Filter removes the filter from the BDE Engine releasing all resources allocated by the engine for the filter.

After dropping a filter you would need to prepare the filter again before it could be activated.


DeActivate
DeActivate Method

Applies to

TFilter, TFilterFunc components

Declaration

procedure DeActivate;

Description

Deactivates  or temporarily removes the current filter, this does not release resources allocated by the BDE Engine for this resource. To free all resources use the RemoveFilter method.
Calling the UnPrepare method or setting prepared to False will DeActivate, then remove the current filter but will also clear the FilterConditions.


DeleteFilterCondition

Applies to

TFilter component

Declaration

procedure DeleteFilterCondition( Index:integer )

Description

Removes the FilterCondition object identified in the list of filter FilterCondition at the index specified by the Index parameter. This is a low level procedure and is not normally used. If you remove a filter condition you are responsible for making any required changes to the LinkOperators of the remaining filter conditions to ensure that the filter will be valid when prepared.


FilterCount Property

Applies to

TFilter component

Declaration

property FilterCount :integer;

Description

This property returns a count of the FilterCondition objects in the current filter list.


GoFirst Property

Applies to

TFilter, TFilterFunc components

Declaration

property GoFirst: boolean;

Description

Set this property to True to cause the record postion to move to the first record in the Dataset that matches the filter criteria whenever the filter is activated or deactivated. If the property is set to false the record position moves to the next record after the current record that matches the filter criteria.


Handle
KHandle Property

Applies to

TFilter TFilterFunc components

Declaration

property Handle: hDBiFilter

Description

The hDBiFilter Handle returned by the BDE Engine that identifies the filter to the BDE Engine.


License Agreement

Important

By using this software you accept the following terms of this License Agreement.  If you do not agree with these terms, you should not use the software and promptly return it for a refund.

Ownership

Visual Solutions Ltd. retains the ownership of this copy of the enclosed software package.  It is licensed to you for use under the following conditions:

You May

You may transfer this software to another party if the other party agrees to the terms and conditions of the agreement and completes and returns a registration card to Visual Solutions Ltd.  The registration card is available by writing to Visual Solutions Ltd.  If you transfer the software, you must simultaneously transfer all documentation and related disks.

You May Not

You may not copy the documentation or software except as described in the installation section of this manual.  You may not distribute, rent, sub-license or lease the software or documentation, including translating, decompiling, disassembling, or creating derivative works.  You may not reverse-engineer any part of this software, or produce any derivative work.  You may not make telecommunication transmittal of this software.

Termination

This license and your right to use this software automatically terminates if you fail to comply with any provision of this license agreement.

Rights

Visual Solutions Ltd. retains all rights not expressly granted.  Nothing in this license agreement constitutes a waiver of Visual Solutions Ltd.'s rights under the H.K. copyright laws or any other law.

Limited Warranty

If you discover physical defects in the media, Visual Solutions Ltd. will replace the media or documentation at no charge to you, provided you return the item to be replaced with proof of payment to Visual Solutions Ltd. during the 90-day period after having taken delivery of the software.

License Agreement

Visual Solutions Ltd.excludes any and all implied warranties, including warranties of merchantability and fitness for a particular purpose and limits your remedy to return the software and documentation to Visual Solutions Ltd. for replacement.
Although Visual Solutions Ltd. has tested the software and reviewed the documentation, Visual Solutions Ltd. MAKES NO WARRANTY OF REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS SOFTWARE OR DOCUMENTATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.  AS A RESULT, THIS SOFTWARE AND DOCUMENTATION ARE LICENSED "AS IS" AND YOU, THE LICENSEE, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE.

IN NO EVENT WILL Visual Solutions Ltd. BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION, even if advised of the possibility of such damages. In particular, Visual Solutions Ltd. shall have no liability for any data stored or processed with this software, including the costs of recovering such data.
THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESSED OR IMPLIED.  No Visual Solutions Ltd. dealer, agent, or employee is authorized to make any modifications or additions to this warranty.

Information in this document is subject to change without notice and does not represent a commitment on the part of Visual Solutions Ltd.  The software described in this document is furnished under this license agreement.  The software may be used or copied only in accordance with the terms of the
agreement.  It is against the law to copy the software on any medium except as specifically allowed in the license agreement.  No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the written permission of Visual Solutions Ltd.

Some countries do not allow the exclusion of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you.  This warranty gives you specific legal rights, and you may also have other rights which vary from country to country.


LoadFromFile Method

Applies to

TFilter component

Declaration

procedure LoadFromFile (AFileName :string);

Description

Loads the filter from the file specified in the AFilename property. You must set the Dataset property before loading the filter. The procedure does not check if the filter conditions match the current dataset but an inavlid filter condition will be rejected by the BDE and the filter will not be able to be activated.


OnFilterRecord
OnFilterRecord Event

Applies to

TFilterFunc component

Declaration

property OnFilterRecord :TFilterEvent

Description

Event raised when a record needs to be cheked as to wether its should be displayed or not.
You can access any field in the dataset using the TField objects to determine wether the current record matches criteria that you set.
Set the RESULT value of the function to True to include this record in the visible record set to False to reject the record.
You MUST not use any method that moves the record pointer or changes the dataset state during this function.

{TFilterFunc - OnFilter Event}
TFilterEvent = function(Sender:TObject; DataSet:TDataSet):Boolean of object;


Prepare
KPrepare Property

Applies to

TFilter component

Declaration

procedure Prepare ;

Description

Prepares the current filter by parsing the FilterConditions object in the TList and then submitting the resultant buffer to the BDE engine where it is added to the list of filters. The filter is not activated by this procedure.
If there is a BDE Filter already set for this component (the Handle property is not nil ) then the filter is first dropped before preparing the new filter.

If the AutoPack property is set to True then after the filter has been created the FilterCondition objects are freed.


Prepared
Prepared Property

Applies to

TFilter component

Declaration

property Prepared: Boolean

Description

Setting this property to True calls the prepare method to prepare the current filter. Set to false to call unprepare method for the filter.


RemoveFilter
RemoveFilter Method

Applies to

TFilter component

Declaration

procedure RemoveFilter ;

Description

Removes the current filter, freeing all resource allocated by the BDE Engine for this filter. This procedure does not release any FilterCondition objects. These must be freed either using the ClearFilterConditions method or setting the prepared property to False or calling the UnPrepare method.


SaveToFile Method

Applies to

TFilter component

Declaration

procedure SaveToFile ( AFileName :string);

Description

Saves the currently defined filter to the file named in the AFileName parameter.
The filter is saved in the BDE canOP language form.


Unprepare
KUnprepare Method

Applies to

TFilter component

Declaration

procedure Unprepare;

Description

If there is a prepared filter it will be DeActivated and then removed (releasing all BDE resources) before freeing all FilterConditions objects.


Activate

<Activate>


Active

<Active>


Add

<Add Method>


AddFilter

<AddFilter>


AddFilterCondition

<AddFilterCondition Method>


AutoActivate

<AutoActivate Property>


ClearFilterConditions

<ClearFilterConditions>


Conditions

<Conditions>


Dataset

<Dataset>


Datasource

<Datasource>


DBActivate

<DBActivateFilter Method>


DBAddFilter

<DBAddFilter Method>


DBDeActivate

<DBDeActivateFilter Method>


DBDropFilter

<DBDropFilter Method>


DeActivate

<DeActivate>


DeleteFilterCondition

<DeleteFilterCondition>


FilterCount

<FilterCount>


GoFirst

<GoFirst Property>


Handle

<Handle>


HFilter

<HFilter>


OnFilterRecord

<OnFilterRecord>


Prepare

<Prepare>


Prepared

<Prepared>


RemoveFilter

<RemoveFilter>


UnPrepare

<Unprepare>